Events

Properties

Methods

Notes

Sizing and Positioning the SpriteSurface Area

The SpriteSurface control can be added to a window and resized by dragging or by assigning values to the The Left, Top, Width, and Height properties. These properties are read/write and can be used to change the size and location of the SpriteSurface on-the-fly.

You can also use two properties of the parent window, FullScreen and MenuBarVisible, to allow the SpriteSurface object to take over the user's entire screen area. Set FullScreen to True and MenuBarVisible to False and use the SpriteSurface's Lock... properties to lock the SpriteSurface control to the parent window so that the SpriteSurface area expands automatically. This sets the Left, Top, Width, and Height properties accordingly.

Creating Animation with Sprites

The SpriteSurface control is used to create animation where pictures can be moved around the screen with all redrawing handled automatically by the SpriteSurface control. Each picture is a Sprite object. Sprite objects have x and y properties that determine their current location on the screen when the SpriteSurface is running the sprite animation.

Causing Sprites to Move and Change Images

The NextFrame event handler is called each time the SpriteSurface is ready to draw the next frame of animation. If you want a Sprite to change position in the next frame, change its x and/or y properties in the NextFrame event handler. If you want the Sprite's picture to change in the next frame of animation, change its Image property in the NextFrame event handler. Use the Update method to run the animation one step at a time. It calls the NextFrame event handler only once.

To remove a Sprite from the animation, simply call the Sprite's Close method.

Frame Redrawing

The speed at which frames are redrawn is based on the FrameSpeed property. The higher the FrameSpeed, the faster the animation will run.

The safest way to run the animation is to update it via a Timer. Add a Timer to the window that contains the SpriteSurface. Adjust its Period property according to how fast you want the animation to go and set its Mode to 2 (Multiple). In its Action event, call the SpriteSurface's Update method.

You can also call the SpriteSurface's Run method, but this puts the application in a modal state, which can cause other problems. Call the Update method via the Timer if you want to allow the user to use the mouse and keyboard during the animation.

To stop the animation, call the SpriteSurface's Close method.

Current Implementation

The size and position of the SpriteSurface area are controlled by the Left, Top, Height, and Width properties or by setting the parent window's FullScreen property to True and using the LockLeft, LockTop, LockRight, and LockBottom properties to automatically expand the SpriteSurface area as the window expands.

Once the Run method is called, NextFrame events will continue to be called until the user clicks the mouse button if the ClickToStop property is True. If ClickToStop is False, the animation will continue until the window that the SpriteSurface is on closes.

Examples

In this example, a Sprite is moved back and forth horizontally across the screen. The PushButton's Action event handler creates a Sprite and stores it in a window property of type Sprite named LisaSprite. The image for the LisaSprite object is a pict image called LisaPict that has been dragged into the Project Editor. The SpriteSurface control named SpriteSurface1 will control the animation. The PushButton then begins the animation by calling the Run method of the SpriteSurface1 control. Another window property of type Integer named LisaDirection is used to keep track of the direction of the LisaSprite. Here are the event handlers:

Pushbutton1:

SpriteSurface1:

The Timer in the window calls the SpriteSurface's Update method in its Action event. It's mode is set to 2.

This example closes (using the Close method) the running SpriteSurface control when the user presses the Return key:

A more sophisticated example called "REALSimpleSprites" that uses a new class to control sprites is available at our ftp site and on the REALbasic CD.

The following example uses the PaintTile event to animate the screen image when the user presses an arrow key. The PaintTile event occurs when the scroll method is called.

The SpriteSurface's NextFrame event has the following code:

Each condition tests whether the user pressed an arrow key and calls the scroll method with appropriate x and y values. The PaintTile event has the following code:

See Also

Sprite object.